Summary

When using oceanbase-sqlalchemy to connect to OceanBase Oracle tenant databases, queries that use reserved words as parameter names (e.g., :start, :end) fail with:

OBE-01036: illegal variable name/number

Issue:

• ✅ Using oracle+cx_oracle to connect to Oracle database: Works successfully
• ❌ Using oceanbase+cx_oceanbase to connect to OceanBase database: Fails with error

Error Example:

query = text("""
    SELECT * FROM table
    WHERE date BETWEEN :start AND :end
""")

params = {'start': date(2025, 2, 12), 'end': date(2025, 2, 19)}

❌ OceanBase error: OBE-01036

Generated SQL:

WHERE date BETWEEN :"start" AND :end

Root Cause

This is a database kernel-level design difference:

SQLAlchemy's Oracle dialect automatically adds quotes to reserved word parameter names during SQL compilation (via OracleCompiler_cx_oracle.bindparam_string), but OceanBase's database kernel does not support quoted parameter names.

Solution

Override bindparam_string in OceanBaseCompiler_cx_oracle to skip Oracle's quoting logic by directly calling the parent OracleCompiler.bindparam_string, avoiding quotes on parameter names.

Key Changes:

1. Create custom compiler OceanBaseCompiler_cx_oracle inheriting from OracleCompiler_cx_oracle
2. Override bindparam_string to skip the quoting branch
3. For SQLAlchemy 2.0+, preserve numeric/underscore prefix normalization logic (:123start → :D123start) since SQLAlchemy 2.0+ natively supports this

Solution Description